<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>
  Class: OpenTok::OpenTok
  
    &mdash; Documentation by YARD 0.8.7.6
  
</title>

  <link rel="stylesheet" href="../css/style.css" type="text/css" charset="utf-8" />

  <link rel="stylesheet" href="../css/common.css" type="text/css" charset="utf-8" />

<script type="text/javascript" charset="utf-8">
  hasFrames = window.top.frames.main ? true : false;
  relpath = '../';
  framesUrl = "../frames.html#!OpenTok/OpenTok.html";
</script>


  <script type="text/javascript" charset="utf-8" src="../js/jquery.js"></script>

  <script type="text/javascript" charset="utf-8" src="../js/app.js"></script>


  </head>
  <body>
    <div id="header">
      <div id="menu">
  
    <a href="../_index.html">Index (O)</a> &raquo;
    <span class='title'><span class='object_link'><a href="../OpenTok.html" title="OpenTok (module)">OpenTok</a></span></span>
     &raquo; 
    <span class="title">OpenTok</span>
  

  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
</div>

      <div id="search">
  
    <a class="full_list_link" id="class_list_link"
        href="../class_list.html">
      Class List
    </a>
  
    <a class="full_list_link" id="method_list_link"
        href="../method_list.html">
      Method List
    </a>
  
    <a class="full_list_link" id="file_list_link"
        href="../file_list.html">
      File List
    </a>
  
</div>
      <div class="clear"></div>
    </div>

    <iframe id="search_frame"></iframe>

    <div id="content"><h1>Class: OpenTok::OpenTok
  
  
  
</h1>

<dl class="box">
  
    <dt class="r1">Inherits:</dt>
    <dd class="r1">
      <span class="inheritName">Object</span>
      
        <ul class="fullTree">
          <li>Object</li>
          
            <li class="next">OpenTok::OpenTok</li>
          
        </ul>
        <a href="#" class="inheritanceTree">show all</a>
      
      </dd>
    
  
  
    
  
    
  
  
  
    <dt class="r2 last">Defined in:</dt>
    <dd class="r2 last">lib/opentok/opentok.rb</dd>
  
</dl>
<div class="clear"></div>

<h2>Overview</h2><div class="docstring">
  <div class="discussion">
    
<p>Contains methods for creating OpenTok sessions, generating tokens, and
working with archives.</p>

<p>To create a new OpenTok object, call the OpenTok constructor with your
OpenTok API key and the API secret from the OpenTok dashboard (<a
href="https://dashboard.tokbox.com">dashboard.tokbox.com</a>). Do not
publicly share your API secret. You will use it with the OpenTok
constructor (only on your web server) to create OpenTok sessions.</p>


  </div>
</div>
<div class="tags">
  

</div>
  <h2>Constant Summary</h2>
  







  
    <h2>
      Instance Method Summary
      <small>(<a href="#" class="summary_toggle">collapse</a>)</small>
    </h2>

    <ul class="summary">
      
        <li class="public ">
  <span class="summary_signature">
    
      <a href="#archives-instance_method" title="#archives (instance method)">- (Object) <strong>archives</strong> </a>
    

    
  </span>
  
  
  
  
  
  
  

  
    <span class="summary_desc"><div class='inline'>
<p>An Archives object, which lets you work with OpenTok archives.</p>
</div></span>
  
</li>

      
        <li class="public ">
  <span class="summary_signature">
    
      <a href="#create_session-instance_method" title="#create_session (instance method)">- (Session) <strong>create_session</strong>(opts = {}) </a>
    

    
  </span>
  
  
  
  
  
  
  

  
    <span class="summary_desc"><div class='inline'>
<p>Creates a new OpenTok session and returns the session ID, which uniquely
identifies the session.</p>
</div></span>
  
</li>

      
        <li class="public ">
  <span class="summary_signature">
    
      <a href="#generate_token-instance_method" title="#generate_token (instance method)">- (String) <strong>generate_token</strong>(options) </a>
    

    
  </span>
  
  
  
  
  
  
  

  
    <span class="summary_desc"><div class='inline'>
<p>Generates a token for a given session.</p>
</div></span>
  
</li>

      
        <li class="public ">
  <span class="summary_signature">
    
      <a href="#initialize-instance_method" title="#initialize (instance method)">- (OpenTok) <strong>initialize</strong>(api_key, api_secret, api_url = ::OpenTok::API_URL) </a>
    

    
  </span>
  
  
    <span class="note title constructor">constructor</span>
  
  
  
  
  
  

  
    <span class="summary_desc"><div class='inline'>
<p>Create a new OpenTok object.</p>
</div></span>
  
</li>

      
    </ul>
  


  
  
  
  
  
  <div id="constructor_details" class="method_details_list">
  <h2>Constructor Details</h2>
  
    <div class="method_details first">
  <h3 class="signature first" id="initialize-instance_method">
  
    - (<tt><span class='object_link'><a href="" title="OpenTok::OpenTok (class)">OpenTok</a></span></tt>) <strong>initialize</strong>(api_key, api_secret, api_url = ::OpenTok::API_URL) 
  

  

  
</h3><div class="docstring">
  <div class="discussion">
    
<p>Create a new OpenTok object.</p>


  </div>
</div>
<div class="tags">
  <p class="tag_title">Parameters:</p>
<ul class="param">
  
    <li>
      
        <span class='name'>api_key</span>
      
      
        <span class='type'>(<tt>String</tt>)</span>
      
      
      
        &mdash;
        <div class='inline'>
<p>Your OpenTok API key. See the OpenTok dashboard (<a
href="https://dashboard.tokbox.com">dashboard.tokbox.com</a>).</p>
</div>
      
    </li>
  
    <li>
      
        <span class='name'>api_secret</span>
      
      
        <span class='type'>(<tt>String</tt>)</span>
      
      
      
        &mdash;
        <div class='inline'>
<p>Your OpenTok API key.</p>
</div>
      
    </li>
  
    <li>
      
        <span class='name'>api_url</span>
      
      
        <span class='type'>(<tt>String</tt>)</span>
      
      
        <em class="default">(defaults to: <tt>::OpenTok::API_URL</tt>)</em>
      
      
        &mdash;
        <div class='inline'>
<p>Do not set this parameter. It is for internal use by TokBox.</p>
</div>
      
    </li>
  
</ul>


</div><table class="source_code">
  <tr>
    <td>
      <pre class="lines">


68
69
70
71
72
73
74</pre>
    </td>
    <td>
      <pre class="code"><span class="info file"># File 'lib/opentok/opentok.rb', line 68</span>

<span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_api_key'>api_key</span><span class='comma'>,</span> <span class='id identifier rubyid_api_secret'>api_secret</span><span class='comma'>,</span> <span class='id identifier rubyid_api_url'>api_url</span><span class='op'>=</span><span class='op'>::</span><span class='const'>OpenTok</span><span class='op'>::</span><span class='const'>API_URL</span><span class='rparen'>)</span>
  <span class='ivar'>@api_key</span> <span class='op'>=</span> <span class='id identifier rubyid_api_key'>api_key</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='rparen'>)</span>
  <span class='ivar'>@api_secret</span> <span class='op'>=</span> <span class='id identifier rubyid_api_secret'>api_secret</span>
  <span class='comment'># TODO: do we really need a copy of this in the instance or should we overwrite the module
</span>  <span class='comment'># constant so that other objects can access the same copy?
</span>  <span class='ivar'>@api_url</span> <span class='op'>=</span> <span class='id identifier rubyid_api_url'>api_url</span>
<span class='kw'>end</span></pre>
    </td>
  </tr>
</table>
</div>
  
</div>


  <div id="instance_method_details" class="method_details_list">
    <h2>Instance Method Details</h2>

    
      <div class="method_details first">
  <h3 class="signature first" id="archives-instance_method">
  
    - (<tt>Object</tt>) <strong>archives</strong> 
  

  

  
</h3><div class="docstring">
  <div class="discussion">
    
<p>An Archives object, which lets you work with OpenTok archives.</p>


  </div>
</div>
<div class="tags">
  

</div><table class="source_code">
  <tr>
    <td>
      <pre class="lines">


171
172
173</pre>
    </td>
    <td>
      <pre class="code"><span class="info file"># File 'lib/opentok/opentok.rb', line 171</span>

<span class='kw'>def</span> <span class='id identifier rubyid_archives'>archives</span>
  <span class='ivar'>@archives</span> <span class='op'>||=</span> <span class='const'>Archives</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='id identifier rubyid_client'>client</span>
<span class='kw'>end</span></pre>
    </td>
  </tr>
</table>
</div>
    
      <div class="method_details ">
  <h3 class="signature " id="create_session-instance_method">
  
    - (<tt><span class='object_link'><a href="Session.html" title="OpenTok::Session (class)">Session</a></span></tt>) <strong>create_session</strong>(opts = {}) 
  

  

  
</h3><div class="docstring">
  <div class="discussion">
    
<p>Creates a new OpenTok session and returns the session ID, which uniquely
identifies the session.</p>

<p>For example, when using the OpenTok JavaScript library, use the session ID
when calling the OT.initSession()&lt;/a&gt; method (to initialize an
OpenTok session).</p>

<p>OpenTok sessions do not expire. However, authentication tokens do expire
(see the generateToken() method). Also note that sessions cannot explicitly
be destroyed.</p>

<p>A session ID string can be up to 255 characters long.</p>

<p>Calling this method results in an OpenTokException in the event of an
error. Check the error message for details.</p>

<p>You can also create a session using the OpenTok REST API (see <a
href="http://www.tokbox.com/opentok/api/#session_id_production">www.tokbox.com/opentok/api/#session_id_production</a>)
or the OpenTok dashboard (see <a
href="https://dashboard.tokbox.com/projects">dashboard.tokbox.com/projects</a>).</p>


  </div>
</div>
<div class="tags">
  <p class="tag_title">Parameters:</p>
<ul class="param">
  
    <li>
      
        <span class='name'>opts</span>
      
      
        <span class='type'>(<tt>Hash</tt>)</span>
      
      
        <em class="default">(defaults to: <tt>{}</tt>)</em>
      
      
        &mdash;
        <div class='inline'>
<p>(Optional) This hash defines options for the session.</p>
</div>
      
    </li>
  
</ul>

  
    
    
    <p class="tag_title">Options Hash (<tt>opts</tt>):</p>
    <ul class="option">
      
        <li>
          <span class="name">:media_mode</span>
          <span class="type">(<tt>Symbol</tt>)</span>
          <span class="default">
            
          </span>
          
            &mdash; <div class='inline'>
<p>Determines whether the session will transmit streams the using OpenTok
Media Router (<tt>:routed</tt>) or not (<tt>:relayed</tt>). By default,
this property is set to <tt>:relayed</tt>.</p>

<p>With the <tt>media_mode</tt> property set to <tt>:relayed</tt>, the session
will attempt to transmit streams directly between clients. If clients
cannot connect due to firewall restrictions, the session uses the OpenTok
TURN server to relay audio-video streams.</p>

<p>With the <tt>media_mode</tt> property set to <tt>:routed</tt>, the session
will use the
<a href="https://tokbox.com/opentok/tutorials/create-session/#media-mode" target="_parent" title="OpenTok Media Router">OpenTok Media Router</a>. The OpenTok Media Router provides the following benefits:</p>
<ul><li>
<p>The OpenTok Media Router can decrease bandwidth usage in multiparty
sessions. (When the <tt>media_mode</tt> property is set to
<tt>:relayed</tt>, each client must send a separate audio-video stream to
each client subscribing to it.)</p>
</li><li>
<p>The OpenTok Media Router can improve the quality of the user experience
through <a href="https://tokbox.com/platform/fallback" target="_parent" title="audio fallback and video recovery">audio fallback and video recovery</a>. With these features, if a client’s connectivity degrades to a
degree that it does not support video for a stream it’s subscribing to, the
video is dropped on that client (without affecting other clients), and the
client receives audio only. If the client’s connectivity improves, the
video returns.</p>
</li><li>
<p>The OpenTok Media Router supports the
<a href="https://tokbox.com/opentok/tutorials/archiving" target="_parent" title="archiving">archiving</a> feature, which
lets you record, save, and retrieve OpenTok sessions.</p>
</li></ul>
</div>
          
        </li>
      
        <li>
          <span class="name">:location</span>
          <span class="type">(<tt>String</tt>)</span>
          <span class="default">
            
          </span>
          
            &mdash; <div class='inline'>
<p>An IP address that the OpenTok servers will use to situate the session in
its global network. If you do not set a location hint, the OpenTok servers
will be based on the first client connecting to the session.</p>
</div>
          
        </li>
      
        <li>
          <span class="name">:archive_mode</span>
          <span class="type">(<tt>Symbol</tt>)</span>
          <span class="default">
            
          </span>
          
            &mdash; <div class='inline'>
<p>Determines whether the session will be archived automatically
(<tt>:always</tt>) or not (<tt>:manual</tt>). When using automatic
archiving, the session must use the <tt>:routed</tt> media mode.</p>
</div>
          
        </li>
      
    </ul>
  

<p class="tag_title">Returns:</p>
<ul class="return">
  
    <li>
      
      
        <span class='type'>(<tt><span class='object_link'><a href="Session.html" title="OpenTok::Session (class)">Session</a></span></tt>)</span>
      
      
      
        &mdash;
        <div class='inline'>
<p>The Session object. The session_id property of the object is the session
ID.</p>
</div>
      
    </li>
  
</ul>

</div><table class="source_code">
  <tr>
    <td>
      <pre class="lines">


132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168</pre>
    </td>
    <td>
      <pre class="code"><span class="info file"># File 'lib/opentok/opentok.rb', line 132</span>

<span class='kw'>def</span> <span class='id identifier rubyid_create_session'>create_session</span><span class='lparen'>(</span><span class='id identifier rubyid_opts'>opts</span><span class='op'>=</span><span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>

  <span class='comment'># normalize opts so all keys are symbols and only include valid_opts
</span>  <span class='id identifier rubyid_valid_opts'>valid_opts</span> <span class='op'>=</span> <span class='lbracket'>[</span> <span class='symbol'>:media_mode</span><span class='comma'>,</span> <span class='symbol'>:location</span><span class='comma'>,</span> <span class='symbol'>:archive_mode</span> <span class='rbracket'>]</span>
  <span class='id identifier rubyid_opts'>opts</span> <span class='op'>=</span> <span class='id identifier rubyid_opts'>opts</span><span class='period'>.</span><span class='id identifier rubyid_inject'>inject</span><span class='lparen'>(</span><span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_m'>m</span><span class='comma'>,</span><span class='lparen'>(</span><span class='id identifier rubyid_k'>k</span><span class='comma'>,</span><span class='id identifier rubyid_v'>v</span><span class='rparen'>)</span><span class='op'>|</span>
    <span class='kw'>if</span> <span class='id identifier rubyid_valid_opts'>valid_opts</span><span class='period'>.</span><span class='id identifier rubyid_include?'>include?</span> <span class='id identifier rubyid_k'>k</span><span class='period'>.</span><span class='id identifier rubyid_to_sym'>to_sym</span>
      <span class='id identifier rubyid_m'>m</span><span class='lbracket'>[</span><span class='id identifier rubyid_k'>k</span><span class='period'>.</span><span class='id identifier rubyid_to_sym'>to_sym</span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='id identifier rubyid_v'>v</span>
    <span class='kw'>end</span>
    <span class='id identifier rubyid_m'>m</span>
  <span class='kw'>end</span>

  <span class='comment'># keep opts around for Session constructor, build REST params
</span>  <span class='id identifier rubyid_params'>params</span> <span class='op'>=</span> <span class='id identifier rubyid_opts'>opts</span><span class='period'>.</span><span class='id identifier rubyid_clone'>clone</span>

  <span class='comment'># anything other than :relayed sets the REST param to &quot;disabled&quot;, in which case we force
</span>  <span class='comment'># opts to be :routed. if we were more strict we could raise an error when the value isn't
</span>  <span class='comment'># either :relayed or :routed
</span>  <span class='kw'>if</span> <span class='id identifier rubyid_params'>params</span><span class='period'>.</span><span class='id identifier rubyid_delete'>delete</span><span class='lparen'>(</span><span class='symbol'>:media_mode</span><span class='rparen'>)</span> <span class='op'>==</span> <span class='symbol'>:routed</span>
    <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>p2p.preference</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>disabled</span><span class='tstring_end'>&quot;</span></span>
  <span class='kw'>else</span>
    <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>p2p.preference</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>enabled</span><span class='tstring_end'>&quot;</span></span>
    <span class='id identifier rubyid_opts'>opts</span><span class='lbracket'>[</span><span class='symbol'>:media_mode</span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='symbol'>:relayed</span>
  <span class='kw'>end</span>
  <span class='comment'># location is optional, but it has to be an IP address if specified at all
</span>  <span class='kw'>unless</span> <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:location</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_nil?'>nil?</span>
    <span class='id identifier rubyid_raise'>raise</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>location must be an IPv4 address</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>unless</span> <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:location</span><span class='rbracket'>]</span> <span class='op'>=~</span> <span class='const'>Resolv</span><span class='op'>::</span><span class='const'>IPv4</span><span class='op'>::</span><span class='const'>Regex</span>
  <span class='kw'>end</span>
  <span class='comment'># archive mode is optional, but it has to be one of the valid values if present
</span>  <span class='kw'>unless</span> <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:archive_mode</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_nil?'>nil?</span>
    <span class='id identifier rubyid_raise'>raise</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>archive mode must be either always or manual</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>unless</span> <span class='const'>ARCHIVE_MODES</span><span class='period'>.</span><span class='id identifier rubyid_include?'>include?</span> <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:archive_mode</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_to_sym'>to_sym</span>
  <span class='kw'>end</span>

  <span class='id identifier rubyid_raise'>raise</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>A session with always archive mode must also have the routed media mode.</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>if</span> <span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:archive_mode</span><span class='rbracket'>]</span> <span class='op'>==</span> <span class='symbol'>:always</span> <span class='op'>&amp;&amp;</span> <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:media_mode</span><span class='rbracket'>]</span> <span class='op'>==</span> <span class='symbol'>:relayed</span><span class='rparen'>)</span>

  <span class='id identifier rubyid_response'>response</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_create_session'>create_session</span><span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span><span class='rparen'>)</span>
  <span class='const'>Session</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='id identifier rubyid_api_key'>api_key</span><span class='comma'>,</span> <span class='id identifier rubyid_api_secret'>api_secret</span><span class='comma'>,</span> <span class='id identifier rubyid_response'>response</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>sessions</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Session</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>session_id</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='id identifier rubyid_opts'>opts</span>
<span class='kw'>end</span></pre>
    </td>
  </tr>
</table>
</div>
    
      <div class="method_details ">
  <h3 class="signature " id="generate_token-instance_method">
  
    - (<tt>String</tt>) <strong>generate_token</strong>(options) 
  

  

  
</h3><div class="docstring">
  <div class="discussion">
    
<p>Generates a token for a given session.</p>


  </div>
</div>
<div class="tags">
  <p class="tag_title">Parameters:</p>
<ul class="param">
  
    <li>
      
        <span class='name'>session_id</span>
      
      
        <span class='type'>(<tt>String</tt>)</span>
      
      
      
        &mdash;
        <div class='inline'>
<p>The session ID of the session to be accessed by the client using the token.</p>
</div>
      
    </li>
  
    <li>
      
        <span class='name'>options</span>
      
      
        <span class='type'>(<tt>Hash</tt>)</span>
      
      
      
        &mdash;
        <div class='inline'>
<p>A hash defining options for the token.</p>
</div>
      
    </li>
  
</ul>

  
    
    
    <p class="tag_title">Options Hash (<tt>options</tt>):</p>
    <ul class="option">
      
        <li>
          <span class="name">:role</span>
          <span class="type">(<tt>Symbol</tt>)</span>
          <span class="default">
            
          </span>
          
            &mdash; <div class='inline'>
<p>The role for the token. Set this to one of the following values:</p>
<ul><li>
<p><tt>:subscriber</tt> -- A subscriber can only subscribe to streams.</p>
</li><li>
<p><tt>:publisher</tt> -- A publisher can publish streams, subscribe to
streams, and signal. (This is the default value if you do not specify a
role.)</p>
</li><li>
<p><tt>:moderator</tt> -- In addition to the privileges granted to a
publisher, in clients using the OpenTok.js 2.2 library, a moderator can
call the <tt>forceUnpublish()</tt> and <tt>forceDisconnect()</tt> method of
the Session object.</p>
</li></ul>
</div>
          
        </li>
      
        <li>
          <span class="name">:expire_time</span>
          <span class="type">(<tt>integer</tt>)</span>
          <span class="default">
            
          </span>
          
            &mdash; <div class='inline'>
<p>The expiration time, in seconds since the UNIX epoch. Pass in 0 to use the
default expiration time of 24 hours after the token creation time. The
maximum expiration time is 30 days after the creation time.</p>
</div>
          
        </li>
      
        <li>
          <span class="name">:data</span>
          <span class="type">(<tt>String</tt>)</span>
          <span class="default">
            
          </span>
          
            &mdash; <div class='inline'>
<p>A string containing connection metadata describing the end-user. For
example, you can pass the user ID, name, or other data describing the
end-user. The length of the string is limited to 1000 characters. This data
cannot be updated once it is set.</p>
</div>
          
        </li>
      
    </ul>
  

<p class="tag_title">Returns:</p>
<ul class="return">
  
    <li>
      
      
        <span class='type'>(<tt>String</tt>)</span>
      
      
      
        &mdash;
        <div class='inline'>
<p>The token string.</p>
</div>
      
    </li>
  
</ul>

</div><table class="source_code">
  <tr>
    <td>
      <pre class="lines">


48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181</pre>
    </td>
    <td>
      <pre class="code"><span class="info file"># File 'lib/opentok/opentok.rb', line 48</span>

<span class='kw'>class</span> <span class='const'>OpenTok</span>

  <span class='id identifier rubyid_include'>include</span> <span class='const'>TokenGenerator</span>
  <span class='id identifier rubyid_generates_tokens'>generates_tokens</span><span class='lparen'>(</span><span class='lbrace'>{</span>
    <span class='symbol'>:api_key</span> <span class='op'>=&gt;</span> <span class='tlambda'>-&gt;</span><span class='lparen'>(</span><span class='id identifier rubyid_instance'>instance</span><span class='rparen'>)</span> <span class='tlambeg'>{</span> <span class='id identifier rubyid_instance'>instance</span><span class='period'>.</span><span class='id identifier rubyid_api_key'>api_key</span> <span class='rbrace'>}</span><span class='comma'>,</span>
    <span class='symbol'>:api_secret</span> <span class='op'>=&gt;</span> <span class='tlambda'>-&gt;</span><span class='lparen'>(</span><span class='id identifier rubyid_instance'>instance</span><span class='rparen'>)</span> <span class='tlambeg'>{</span> <span class='id identifier rubyid_instance'>instance</span><span class='period'>.</span><span class='id identifier rubyid_api_secret'>api_secret</span> <span class='rbrace'>}</span>
  <span class='rbrace'>}</span><span class='rparen'>)</span>

  <span class='comment'># @private
</span>  <span class='comment'># don't want these to be mutable, may cause bugs related to inconsistency since these values are
</span>  <span class='comment'># cached in objects that this can create
</span>  <span class='id identifier rubyid_attr_reader'>attr_reader</span> <span class='symbol'>:api_key</span><span class='comma'>,</span> <span class='symbol'>:api_secret</span><span class='comma'>,</span> <span class='symbol'>:api_url</span>

  <span class='comment'>##
</span>  <span class='comment'># Create a new OpenTok object.
</span>  <span class='comment'>#
</span>  <span class='comment'># @param [String] api_key Your OpenTok API key. See the OpenTok dashboard
</span>  <span class='comment'>#   (https://dashboard.tokbox.com).
</span>  <span class='comment'># @param [String] api_secret Your OpenTok API key.
</span>  <span class='comment'># @param [String] api_url Do not set this parameter. It is for internal use by TokBox.
</span>  <span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_api_key'>api_key</span><span class='comma'>,</span> <span class='id identifier rubyid_api_secret'>api_secret</span><span class='comma'>,</span> <span class='id identifier rubyid_api_url'>api_url</span><span class='op'>=</span><span class='op'>::</span><span class='const'>OpenTok</span><span class='op'>::</span><span class='const'>API_URL</span><span class='rparen'>)</span>
    <span class='ivar'>@api_key</span> <span class='op'>=</span> <span class='id identifier rubyid_api_key'>api_key</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='rparen'>)</span>
    <span class='ivar'>@api_secret</span> <span class='op'>=</span> <span class='id identifier rubyid_api_secret'>api_secret</span>
    <span class='comment'># TODO: do we really need a copy of this in the instance or should we overwrite the module
</span>    <span class='comment'># constant so that other objects can access the same copy?
</span>    <span class='ivar'>@api_url</span> <span class='op'>=</span> <span class='id identifier rubyid_api_url'>api_url</span>
  <span class='kw'>end</span>

  <span class='comment'># Creates a new OpenTok session and returns the session ID, which uniquely identifies
</span>  <span class='comment'># the session.
</span>  <span class='comment'>#
</span>  <span class='comment'># For example, when using the OpenTok JavaScript library, use the session ID when calling the
</span>  <span class='comment'># OT.initSession()&lt;/a&gt; method (to initialize an OpenTok session).
</span>  <span class='comment'>#
</span>  <span class='comment'># OpenTok sessions do not expire. However, authentication tokens do expire (see the
</span>  <span class='comment'># generateToken() method). Also note that sessions cannot explicitly be destroyed.
</span>  <span class='comment'>#
</span>  <span class='comment'># A session ID string can be up to 255 characters long.
</span>  <span class='comment'>#
</span>  <span class='comment'># Calling this method results in an OpenTokException in the event of an error.
</span>  <span class='comment'># Check the error message for details.
</span>  <span class='comment'>#
</span>  <span class='comment'># You can also create a session using the OpenTok REST API (see
</span>  <span class='comment'># http://www.tokbox.com/opentok/api/#session_id_production) or the OpenTok dashboard
</span>  <span class='comment'># (see https://dashboard.tokbox.com/projects).
</span>  <span class='comment'>#
</span>  <span class='comment'># @param [Hash] opts (Optional) This hash defines options for the session.
</span>  <span class='comment'>#
</span>  <span class='comment'># @option opts [Symbol] :media_mode Determines whether the session will transmit streams the
</span>  <span class='comment'>#   using OpenTok Media Router (&lt;code&gt;:routed&lt;/code&gt;) or not (&lt;code&gt;:relayed&lt;/code&gt;).
</span>  <span class='comment'>#   By default, this property is set to &lt;code&gt;:relayed&lt;/code&gt;.
</span>  <span class='comment'>#
</span>  <span class='comment'>#   With the &lt;code&gt;media_mode&lt;/code&gt; property set to &lt;code&gt;:relayed&lt;/code&gt;, the session
</span>  <span class='comment'>#   will attempt to transmit streams directly between clients. If clients cannot connect due to
</span>  <span class='comment'>#   firewall restrictions, the session uses the OpenTok TURN server to relay audio-video
</span>  <span class='comment'>#   streams.
</span>  <span class='comment'>#
</span>  <span class='comment'>#   With the &lt;code&gt;media_mode&lt;/code&gt; property set to &lt;code&gt;:routed&lt;/code&gt;, the session will use
</span>  <span class='comment'>#   the {https://tokbox.com/opentok/tutorials/create-session/#media-mode OpenTok Media Router}.
</span>  <span class='comment'>#   The OpenTok Media Router provides the following benefits:
</span>  <span class='comment'>#
</span>  <span class='comment'>#   * The OpenTok Media Router can decrease bandwidth usage in multiparty sessions.
</span>  <span class='comment'>#     (When the &lt;code&gt;media_mode&lt;/code&gt; property is set to &lt;code&gt;:relayed&lt;/code&gt;,
</span>  <span class='comment'>#     each client must send a separate audio-video stream to each client subscribing to
</span>  <span class='comment'>#     it.)
</span>  <span class='comment'>#   * The OpenTok Media Router can improve the quality of the user experience through
</span>  <span class='comment'>#     {https://tokbox.com/platform/fallback audio fallback and video recovery}. With
</span>  <span class='comment'>#     these features, if a client's connectivity degrades to a degree that
</span>  <span class='comment'>#     it does not support video for a stream it's subscribing to, the video is dropped on
</span>  <span class='comment'>#     that client (without affecting other clients), and the client receives audio only.
</span>  <span class='comment'>#     If the client's connectivity improves, the video returns.
</span>  <span class='comment'>#   * The OpenTok Media Router supports the
</span>  <span class='comment'>#     {https://tokbox.com/opentok/tutorials/archiving archiving}
</span>  <span class='comment'>#     feature, which lets you record, save, and retrieve OpenTok sessions.
</span>  <span class='comment'>#
</span>  <span class='comment'># @option opts [String] :location  An IP address that the OpenTok servers will use to
</span>  <span class='comment'>#     situate the session in its global network. If you do not set a location hint,
</span>  <span class='comment'>#     the OpenTok servers will be based on the first client connecting to the session.
</span>  <span class='comment'>#
</span>  <span class='comment'># @option opts [Symbol] :archive_mode Determines whether the session will be archived
</span>  <span class='comment'>#     automatically (&lt;code&gt;:always&lt;/code&gt;) or not (&lt;code&gt;:manual&lt;/code&gt;). When using automatic
</span>  <span class='comment'>#     archiving, the session must use the &lt;code&gt;:routed&lt;/code&gt; media mode.
</span>  <span class='comment'>#
</span>  <span class='comment'># @return [Session] The Session object. The session_id property of the object is the session ID.
</span>  <span class='kw'>def</span> <span class='id identifier rubyid_create_session'>create_session</span><span class='lparen'>(</span><span class='id identifier rubyid_opts'>opts</span><span class='op'>=</span><span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span>

    <span class='comment'># normalize opts so all keys are symbols and only include valid_opts
</span>    <span class='id identifier rubyid_valid_opts'>valid_opts</span> <span class='op'>=</span> <span class='lbracket'>[</span> <span class='symbol'>:media_mode</span><span class='comma'>,</span> <span class='symbol'>:location</span><span class='comma'>,</span> <span class='symbol'>:archive_mode</span> <span class='rbracket'>]</span>
    <span class='id identifier rubyid_opts'>opts</span> <span class='op'>=</span> <span class='id identifier rubyid_opts'>opts</span><span class='period'>.</span><span class='id identifier rubyid_inject'>inject</span><span class='lparen'>(</span><span class='lbrace'>{</span><span class='rbrace'>}</span><span class='rparen'>)</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_m'>m</span><span class='comma'>,</span><span class='lparen'>(</span><span class='id identifier rubyid_k'>k</span><span class='comma'>,</span><span class='id identifier rubyid_v'>v</span><span class='rparen'>)</span><span class='op'>|</span>
      <span class='kw'>if</span> <span class='id identifier rubyid_valid_opts'>valid_opts</span><span class='period'>.</span><span class='id identifier rubyid_include?'>include?</span> <span class='id identifier rubyid_k'>k</span><span class='period'>.</span><span class='id identifier rubyid_to_sym'>to_sym</span>
        <span class='id identifier rubyid_m'>m</span><span class='lbracket'>[</span><span class='id identifier rubyid_k'>k</span><span class='period'>.</span><span class='id identifier rubyid_to_sym'>to_sym</span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='id identifier rubyid_v'>v</span>
      <span class='kw'>end</span>
      <span class='id identifier rubyid_m'>m</span>
    <span class='kw'>end</span>

    <span class='comment'># keep opts around for Session constructor, build REST params
</span>    <span class='id identifier rubyid_params'>params</span> <span class='op'>=</span> <span class='id identifier rubyid_opts'>opts</span><span class='period'>.</span><span class='id identifier rubyid_clone'>clone</span>

    <span class='comment'># anything other than :relayed sets the REST param to &quot;disabled&quot;, in which case we force
</span>    <span class='comment'># opts to be :routed. if we were more strict we could raise an error when the value isn't
</span>    <span class='comment'># either :relayed or :routed
</span>    <span class='kw'>if</span> <span class='id identifier rubyid_params'>params</span><span class='period'>.</span><span class='id identifier rubyid_delete'>delete</span><span class='lparen'>(</span><span class='symbol'>:media_mode</span><span class='rparen'>)</span> <span class='op'>==</span> <span class='symbol'>:routed</span>
      <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>p2p.preference</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>disabled</span><span class='tstring_end'>&quot;</span></span>
    <span class='kw'>else</span>
      <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>p2p.preference</span><span class='tstring_end'>&quot;</span></span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>enabled</span><span class='tstring_end'>&quot;</span></span>
      <span class='id identifier rubyid_opts'>opts</span><span class='lbracket'>[</span><span class='symbol'>:media_mode</span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='symbol'>:relayed</span>
    <span class='kw'>end</span>
    <span class='comment'># location is optional, but it has to be an IP address if specified at all
</span>    <span class='kw'>unless</span> <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:location</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_nil?'>nil?</span>
      <span class='id identifier rubyid_raise'>raise</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>location must be an IPv4 address</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>unless</span> <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:location</span><span class='rbracket'>]</span> <span class='op'>=~</span> <span class='const'>Resolv</span><span class='op'>::</span><span class='const'>IPv4</span><span class='op'>::</span><span class='const'>Regex</span>
    <span class='kw'>end</span>
    <span class='comment'># archive mode is optional, but it has to be one of the valid values if present
</span>    <span class='kw'>unless</span> <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:archive_mode</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_nil?'>nil?</span>
      <span class='id identifier rubyid_raise'>raise</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>archive mode must be either always or manual</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>unless</span> <span class='const'>ARCHIVE_MODES</span><span class='period'>.</span><span class='id identifier rubyid_include?'>include?</span> <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:archive_mode</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_to_sym'>to_sym</span>
    <span class='kw'>end</span>

    <span class='id identifier rubyid_raise'>raise</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>A session with always archive mode must also have the routed media mode.</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>if</span> <span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:archive_mode</span><span class='rbracket'>]</span> <span class='op'>==</span> <span class='symbol'>:always</span> <span class='op'>&amp;&amp;</span> <span class='id identifier rubyid_params'>params</span><span class='lbracket'>[</span><span class='symbol'>:media_mode</span><span class='rbracket'>]</span> <span class='op'>==</span> <span class='symbol'>:relayed</span><span class='rparen'>)</span>

    <span class='id identifier rubyid_response'>response</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_create_session'>create_session</span><span class='lparen'>(</span><span class='id identifier rubyid_params'>params</span><span class='rparen'>)</span>
    <span class='const'>Session</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='id identifier rubyid_api_key'>api_key</span><span class='comma'>,</span> <span class='id identifier rubyid_api_secret'>api_secret</span><span class='comma'>,</span> <span class='id identifier rubyid_response'>response</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>sessions</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>Session</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>session_id</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='comma'>,</span> <span class='id identifier rubyid_opts'>opts</span>
  <span class='kw'>end</span>

  <span class='comment'># An Archives object, which lets you work with OpenTok archives.
</span>  <span class='kw'>def</span> <span class='id identifier rubyid_archives'>archives</span>
    <span class='ivar'>@archives</span> <span class='op'>||=</span> <span class='const'>Archives</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='id identifier rubyid_client'>client</span>
  <span class='kw'>end</span>

  <span class='id identifier rubyid_protected'>protected</span>

  <span class='kw'>def</span> <span class='id identifier rubyid_client'>client</span>
    <span class='ivar'>@client</span> <span class='op'>||=</span> <span class='const'>Client</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='id identifier rubyid_api_key'>api_key</span><span class='comma'>,</span> <span class='id identifier rubyid_api_secret'>api_secret</span><span class='comma'>,</span> <span class='id identifier rubyid_api_url'>api_url</span>
  <span class='kw'>end</span>

<span class='kw'>end</span></pre>
    </td>
  </tr>
</table>
</div>
    
  </div>

</div>

    <div id="footer">
  Generated on Mon May 25 15:52:46 2015 by
  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
  0.8.7.6 (ruby-1.9.3).
</div>

  </body>
</html>